上一篇記錄了我第一次與第二次使用 Spec Kit 的實驗。第一次，我把整套權限架構交給 AI 一路做到最後，結果整個專案壞掉；第二次，我補上更多需求與技術作法，也改成分段執行，結果確實好很多，方向卻還是慢慢偏掉。
兩次的做法明明不一樣，為什麼最後都沒有走到我要的結果？直到我把兩次實驗放在一起，才發現問題並不是從 implement 才開始。
這張比較圖看起來像是第二次已經把第一次的問題都補起來了。不過，有一件事始終沒有改變：我還是把整套權限架構放在同一份 spec 裡，卻沒有先確認哪些需求還沒講清楚、哪些作法其實還沒有決定。
分段檢查能讓我提早看到問題，卻不會阻止問題發生。第一次會失控，顯然不只是因為我太晚檢查。
我當時雖然知道 spec 後面會接著 plan 與 tasks，卻還不知道一份 spec 應該包含哪些問題、做到哪裡就該停，只覺得既然需求已經寫成規格，AI 應該就不容易做錯。我少做的，是先弄清楚這個大目標裡包含哪些不同問題、有哪些決定還沒做，以及哪些部分適合放在同一份 spec 裡一起實作與驗證。
第一次實驗時，我還預設 codebase 裡既然已經有類似的實作方式，CLAUDE.md 又寫了專案使用的架構與技術，AI 應該就會照著這些內容完成，所以沒有把這次變更需要的技術作法與重要決策完整寫進 plan。第二次雖然補了更多內容，也重新檢查 plan 是否符合專案既有的架構與規範，但我還是沒有繼續追問：裡面的每一個判斷，究竟建立在什麼前提上？那些我沒有寫到的地方，是專案裡早已有答案，還是我們根本還沒討論過？
需求寫得更詳細，通常只是把我已經想到的內容寫得更多。至於那些沒有被說出口的前提、例外與取捨，並不會因為文件變長就自動得到答案。AI 遇到這些空白時，還是只能根據 codebase、CLAUDE.md、前面的 artifacts 與自己的理解繼續往下做；只要它補上的答案和我心裡想的不一樣，方向就會開始偏離。分段檢查可以讓我提早看見這件事，卻不能替我把原本還沒決定的問題變成答案。
說穿了，第一次實驗時，我把「它應該知道」當成了「我已經說清楚」；到了第二次，我雖然真的說得更多，卻還沒有把需求裡沒談清楚的地方找出來。這也是我後來才真正分清楚的事情：把需求寫得更詳細，和把需求釐清，並不是同一件事。
發現方向又開始偏離後，我帶著實作結果重新查看 spec，以及 plan 過程產生的 research、plan 與後續 tasks。這次不是只看每份文件單獨讀起來合不合理，而是拿實際做出來的東西反過來比對：AI 為什麼會做出這個選擇？這個決定最早是從哪一份文件出現的？
這時我才發現，問題不是到了 implement 才突然冒出來。plan 過程產生的 research 裡，已經有一些和 codebase 不符的判斷；不同位置的專案規範之間，也有彼此矛盾的內容。這些內容又繼續出現在 plan 與 tasks 裡，所以 AI 實作時，只是照著前面整理出的方向一路做下去。
比較尷尬的是，這些 artifacts 我當時真的都有看，而且看的當下也覺得滿合理的。直到內容真的被實作出來後，我才發現有些判斷根本對不上專案現況。這其實也很像平常拿到需求時會遇到的狀況：需求文件看起來沒有問題，真的開始改 code 後，才會發現原本沒想到的限制，或是前後接不起來的地方。只是換成 AI 開發後，我把需求整理成更多 artifacts，卻還是掉進了同一個問題裡。
CLAUDE.md 為什麼會互相打架？還記得【Day - 3】留下的問題嗎？constitution 與 CLAUDE.md 都可能放進原則與規範，兩邊到底要怎麼分？這次看到這些規範互相衝突，我才開始真正整理兩份文件的用途。
到了【Day - 4】，我提過自己當時把專案架構、使用技術、命名、分層、測試與各種開發規範都塞進 CLAUDE.md，整份文件甚至超過 1000 行。另一方面，constitution 裡也會放使用函式庫的原則、測試原則與其他長期規範。當同一類事情同時出現在兩份文件裡，寫法只要不一致，AI 讀到的指示就可能互相打架。
後來真的動手整理時，我沒有再替兩份文件各寫一套完整規範，而是先把兩份文件的用途重新分開。constitution 保留專案長期遵循的工程原則與品質要求，例如測試、UI 一致性，以及實作前不能只看文件，還要回到 codebase 找既有做法。CLAUDE.md 則縮成 AI 和我協作時要遵循的基本方式，再把前端與後端的詳細內容分別指向各自的 README。
拿掉專案名稱、framework 與內部細節後，大概可以簡化成這樣：
# constitution.md
## Project Principles
- 新增功能前，先查看 codebase 裡相近的實作
- 文件只能提供方向，實際做法仍要和現有 code 對照
- 新增商業邏輯時，需要補上對應測試
- UI 優先沿用既有元件與設計規則
# CLAUDE.md
Always respond in Traditional Chinese.
## Coding Practices
- 優先選擇容易維護的作法
- 註解說明「為什麼」，不要重複 code 已經表達的事情
- 主動注意 edge cases、安全性與測試範圍
## Frontend
> 詳細架構與開發方式請參考 `front-end/CLAUDE.md`
## Backend
> 詳細架構與開發方式請參考 `back-end/CLAUDE.md`
這是我當時整理後留下的版本。當時我先做的，是把兩份文件重疊最嚴重的部分拆開，不再讓整套架構、技術與規範在兩邊各放一份。在那個版本裡，constitution 比較像是在回答「這個專案長期不能違反什麼」，CLAUDE.md 則是 Claude Code 進入專案後，該怎麼和我協作、又該去哪裡找資料。兩邊偶爾還是可能有些交集，重要的是調整時要一起看，不要讓重疊的內容越寫越不一樣。
constitution 與
CLAUDE.md都不是整理完就永遠不再調整的文件。規格會繼續往下跑，專案也會持續維護，AI 模型的能力與我跟它協作的方式也一直在變，所以這兩份文件當然也要跟著持續維護與調整。
把 constitution 與 CLAUDE.md 分開之後，【Day - 3】留下的另一個問題還沒有解決：既然專案架構、使用的技術與既有規範都已經有地方可以查，為什麼每次執行 plan 時，還要再說一次這次準備怎麼做？
我後來才比較能理解，plan 要補的是「這次變更還沒決定，但實作前必須說清楚的技術內容」。Spec Kit 並沒有替 greenfield 與 brownfield 準備兩套不同的 plan。從頭建立專案時，可能連使用什麼技術、資料怎麼存、架構怎麼安排都還沒決定；修改既有系統時，通常已經有這些基礎，更需要說清楚這次要沿用什麼、改動什麼，以及怎麼接回原本的系統。
greenfield 與 brownfield： greenfield 通常指從頭建立、還沒有既有系統包袱的開發情境；brownfield 則是在已經有 code、架構、功能與各種限制的系統上繼續修改。
當然，既有系統也可能遇到完全沒有做法可以沿用的新功能，或需要引入新技術、調整架構的變更。這些決定還是得在 plan 裡說清楚，不能因為專案已經有架構，就以為這次不需要再規劃。
我第一次實驗面對的就是 brownfield。當時 codebase 與 CLAUDE.md 的確已經提供不少專案背景，但我沒有在 plan 裡說清楚這次權限重構應該沿用哪些設計、哪些地方才是這次要改的範圍。沒有說明的部分，AI 最後只能按照自己的理解補上。說穿了，我把「AI 看得到專案背景」當成了「AI 知道這次該怎麼改」。
到了第二次實驗，我才把這次適合的架構與技術作法補得更完整，做出來的結果也確實比第一次更接近我要的方向。
CLAUDE.md 可以提供專案背景，但不能代替這次變更的 plan。前者寫得再完整，這次準備怎麼改，還是要在 plan 裡說清楚。
不過，就算 plan 的用途分清楚了，前面還有一個更早的問題：spec 裡那些沒說清楚的地方，要在哪一步被找出來？
把問題一路往前追之後，我才想到：Spec Kit 不是還有 clarify 嗎？
它會在 plan 之前，針對 spec 裡還沒寫清楚的地方繼續提問，再把確認後的答案寫回 spec。前兩次實驗時，我把注意力都放在怎麼把需求與 plan 寫得更完整，卻沒有真的把這一步接進自己的 workflow。
於是，我決定把 clarify 接回 workflow，先讓它針對 spec 裡沒說清楚的地方提問，再往 plan 和實作走。但補上這一步之後，AI 就比較能做出我要的結果了嗎？下一篇，就來聊聊補上 clarify 後有哪些改善，以及持續使用 Spec Kit 時，我還想調整哪些流程吧！
iThome鐵人賽
看影片追技術